home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / tlp4v11c / docu / uniinp.txt < prev    next >
Text File  |  1994-05-22  |  11KB  |  345 lines
  1. uniinp.obj function summary:
  2. ============================
  3.  
  4. This list contains UNIX-like summaries for the routines that
  5. are currently contained in uniinpx.obj.
  6.  
  7. uniinpx.obj is intended for use with the tgdlp4xx.obj ModeX
  8. graphics driver. However this library could also act as a stand
  9. alone module. In order for uniinpx.obj to work the following
  10. hardware items are required:
  11.  
  12. - IBM compatible AT with 80286 CPU or above
  13. - MF-II keyboard
  14. - any VGA card
  15.  
  16. uniinpc.obj is assembled for the COMPACT memory model. This
  17. means that all calls to procedures must be declared as NEAR
  18. while pointers to data are all FAR.
  19. uniinpl.obj is assembled for the LARGE memory model. In this
  20. model all calls to procedures as well as all pointers to data
  21. are to be declared as FAR.
  22.  
  23. uniinpx.obj expects all parameters to be passed using C calling
  24. conventions. The C calling mechanism is described in tgdlp4.txt.
  25.  
  26.  
  27. PART I: KEYBOARD FUNCTIONS
  28. ----------------------------------------------------------------
  29.  
  30. byte getkeyboard(void);
  31. install uniinp keyboard interrupt handler
  32.  
  33. FUNCTION:
  34. In order for the functions lastkey(), keystatus() and
  35. freekeyboard() to work the system keyboard handler has to be
  36. replaced by the uniinp keyboard handler. This is done when
  37. calling getkeyboard(). The uniinp keyboard handler never calls
  38. the default system keyboard handler - giving you TOTAL control
  39. over the keyboard. That means if you don't implement it the user
  40. can't even reset her/his AT using Ctrl-Alt-Del.
  41. Note: You should call keyboardled(0) BEFORE getkeyboard() to
  42. assure proper function of the lastkey() and keystatus() routines.
  43.  
  44. INPUTS:
  45. none
  46.  
  47. RESULT:
  48. byte success: TRUE if the uniinp keyboard handler was
  49.           successfully installed,
  50.           FALSE if not (i.e. the uniinp keyboard handler is
  51.           already active).
  52.  
  53. BUGS:
  54. none known
  55.  
  56. SEE ALSO:
  57. freekeyboard(), lastkey(), keystatus(), keyboardled()
  58.  
  59.  
  60. byte freekeyboard(void);
  61. uninstall uniinp keyboard interrupt handler
  62.  
  63. FUNCTION:
  64. Once the uniinp keyboard [lastkey(), keystatus()] services
  65. aren't required anymore the uniinp keyboard interrupt server
  66. should be removed and the default BIOS keyboard handler should
  67. be re-installed. To accomplish this just call freekeyboard()
  68. which returns the keyboard control to the system.
  69. Note: You should call keyboardled(sysled()) AFTER freekeyboard()
  70. to restore the old keyboard LED state (if you have changed it).
  71.  
  72. INPUTS:
  73. none
  74.  
  75. RESULT:
  76. byte success: TRUE if the keyboard was successfully returned to
  77.           the system,
  78.           FALSE if not (i.e. the uniinp keyboard handler was
  79.           not active)
  80.  
  81. BUGS:
  82. none known
  83.  
  84. SEE ALSO:
  85. getkeyboard()
  86.  
  87.  
  88. ubyte lastkey(void);
  89. get uniinp scan code of the key that was pressed/released last
  90.  
  91. FUNCTION:
  92. To find out which key was pressed or released last call this
  93. procedure. It will return the uniinp keycode of the last used
  94. key or 0 if you have already queried the last key or no key was
  95. used since the initialization of the uniinp keyboard handler.
  96. The uniinp keycode is the MF-II scan code of the key if the key
  97. represents a non special character. For example the key 't'
  98. returns scan code 20. If a special key was hit/released the
  99. uniinp keycode of that key is the second byte of the MF-II scan
  100. code + 128. Example: The cursor right key would return 77+128=
  101. 205. To check if a specific key was pressed or released call
  102. keystatus() with the uniinp keycode as parameter.
  103.  
  104. INPUTS:
  105. none
  106.  
  107. RESULT:
  108. ubyte keycode: uniinp keycode of the key that was in use last or
  109.            0 if that key was already queried.
  110.  
  111. BUGS:
  112. none known
  113.  
  114. SEE ALSO:
  115. keystatus()
  116.  
  117.  
  118. byte keystatus(ubyte keycode);
  119. return status of specified key
  120.  
  121. FUNCTION:
  122. This routine returns TRUE if the key of which the uniinp keycode
  123. was passed in keycode is currently held down. It returns FALSE
  124. if this key is currently not pressed. To find out which key was
  125. used last call the lastkey() procedure.
  126.  
  127. INPUTS:
  128. keycode: uniinp keycode of the key of which the status should be
  129.      checked
  130.  
  131. RESULT:
  132. byte keypressed: TRUE if the key is currently pressed,
  133.          FALSE if not.
  134.  
  135. BUGS:
  136. none known
  137.  
  138. SEE ALSO:
  139. lastkey()
  140.  
  141.  
  142. byte keyboardled(ubyte ledstatus);
  143. control for the MF-II keyboard LEDs/state
  144.  
  145. FUNCTION:
  146. keyboardled() allows you to switch on/off the LEDs on a MF-II
  147. keyboard:
  148. bit 0 of ledstatus controls the scroll-lock LED
  149. bit 1 of ledstatus controls the num-lock LED
  150. bit 2 of ledstatus controls the caps-lock LED
  151. Switch on/off a specific LED by setting/resetting the
  152. corresponding bit in ledstatus. Setting/resetting the LED bits
  153. has effects on the key scan code that the keyboard returns to
  154. the computer. For proper function of the lastkey() and
  155. keystatus() procedures it is recommended to switch all keyboard
  156. LEDs off to force the MF-II keyboard to produce 'native' scan
  157. codes.
  158. keyboardled() doesn't use a BIOS routine to set/clear the
  159. LEDs. Therefore when returning from your program you should set
  160. the old BIOS keyboard LED state. To do this, just call
  161. keyboardled(sysled());
  162. keyboardled() should be called before getkeyboard() or after
  163. freekeyboard().
  164.  
  165. INPUTS:
  166. ledstatus: LED status variable:
  167.        bit 0 controls the scroll-lock LED
  168.        bit 1 controls the num-lock LED
  169.        bit 2 controls the caps-lock LED
  170.        to switch on a LED set the corresponding LED bit.
  171.        to switch off a LED clear the corresponding LED bit.
  172.  
  173. RESULT:
  174. byte success: TRUE if the keyboard accepted the new LED settings,
  175.           FALSE if not.
  176.  
  177. BUGS:
  178. none known
  179.  
  180. SEE ALSO:
  181. lastkey(), keystatus(), sysled(), getkeyboard(), freekeyboard()
  182.  
  183.  
  184. byte keyboardtyp(ubyte kbddelay,ubyte kbdtypem);
  185. control for the MF-II keyboard delay and typematic rates
  186.  
  187. FUNCTION:
  188. Using this procedure you can change the MF-II keyboard delay and
  189. typematic rates. The keyboard delay rate represents the period
  190. of time that passes between a key being first holded down and
  191. the key being repeated. You can choose one of these values for
  192. the keyboard delay rate, which must be passed in kbddelay:
  193. value        delay rate
  194.   0           .25 sec
  195.   1           .5  sec
  196.   2                .75 sec
  197.   3          1.0  sec
  198.  
  199. The keyboard typematic rate must be adjusted simultaneously to
  200. the keyboard delay rate and vice versa. The typematic rate is
  201. the number of repetitions per second of a keycode the keyboard
  202. sends after the keyboard delay time has passed. The keyboard
  203. typematic rate is a 5 bit value - hence allowing you to pass
  204. 0-31 as kbdtypem parameter. The value 0 sets the key repeat rate
  205. to 30 times per second while the value 31 sets the key repeat
  206. rate to only 2 times per second.
  207. Once keyboardtyp() is called there is no way to set the previous
  208. keyboard delay / typematic rates that were active before calling
  209. this function. keyboardtyp() should only be called before
  210. getkeyboard() / after freekeyboard().
  211.  
  212. INPUTS:
  213. kbddelay: keyboard delay rate. Allowed values are between 0-3
  214.           (equals a delay of 0.25 - 1.0 sec before key repetition
  215.        begins).
  216. kbdtypem: keyboard repeat rate. Allowed values are between 0-31
  217.       (equals a key repeat rate of 30 - 2 times a second).
  218.  
  219. RESULT:
  220. byte success: TRUE if the keyboard accepted the new delay /
  221.               typematic rates,
  222.           FALSE if not.
  223.  
  224. BUGS:
  225. none known
  226.  
  227. SEE ALSO:
  228. getkeyboard(). freekeyboard()
  229.  
  230.  
  231. ubyte sysled(void);
  232. query the BIOS MF-II keyboard LED values
  233.  
  234. FUNCTION:
  235. In combination with keyboardled() this routine allows setting
  236. the keyboard LEDs as expected to be set by the BIOS. Usefull
  237. when the LED bits were previously changed using keyboardled()
  238. [to i.e. receive proper key scan codes with the lastkey() and
  239. keystatus() procedures]. Just call keyboardled(sysled()) to
  240. set the old BIOS LED state.
  241.  
  242. INPUTS:
  243. none
  244.  
  245. RESULT:
  246. ubyte ledstatus: keyboard LED state which the BIOS expects to be
  247.          set.
  248.  
  249. BUGS:
  250. none known
  251.  
  252. SEE ALSO:
  253. keyboardled()
  254.  
  255.  
  256. PART II: JOYSTICK FUNCTIONS
  257. ----------------------------------------------------------------
  258.  
  259. joypos far *readstick(ubyte stick);
  260. read position(s) of connected joystick(s)
  261.  
  262. FUNCTION:
  263. To make use of this procedure you first have to check which
  264. joystick(s) are connected. Call readstick(1) [readstick(2)] to
  265. see if joystick #0 [joystick #1] is connected. If joystick #0
  266. [#1] is not attached readstick() will return FALSE - otherwise
  267. the specified joystick is connected and the function will return
  268. a pointer to the joystick position structure which looks like
  269. this:
  270. struct { uword joy0xpos,joy0ypos; 
  271.      uword joy1xpos,joy1ypos;
  272.        } joypos;
  273. joy0xpos contains the current x position of joystick #0
  274. joy0ypos contains the current y position of joystick #0
  275. joy1xpos contains the current x position of joystick #1
  276. joy1ypos contains the current y position of joystick #1
  277.  
  278. joystick x,y position values usually range from 0-31 (tested with
  279. Gravis Gamepad/ Gravis Analog joysticks). The joystick position
  280. values returned by readstick() are CPU speed independent.
  281. Notes: a) the values of joy0xpos,joy0ypos [joy1xpos,joy1ypos]
  282.       are undefined when readstick(2) [readstick(1)] was
  283.       called.
  284.        b) use readstick(3) to query the joystick positions of
  285.       both joysticks simultaneously. This is twice as fast
  286.       than a calling combination of readstick(1) and
  287.       readstick(2).
  288.       WARNING: use readstick(3) only when both joysticks are
  289.       REALLY connected - otherwise readstick(3) will return
  290.       FALSE.
  291.        c) It is not allowed to call readstick() while a vertical
  292.       retrace is active. Do a waittof() before using this
  293.       routine.
  294.  
  295. INPUTS:
  296. stick: indicator of which joystick position should be queried:
  297.        if bit 0 is set readstick() reads the position of
  298.                joystick #0.
  299.        if bit 1 is set readstick() reads the position of
  300.                joystick #1.
  301.  
  302. RESULT:
  303. joypos *: pointer to a structure containing the requested
  304.       joystick position(s). The structure looks like this:
  305.       struct { uword joy0xpos,joy0ypos; 
  306.             uword joy1xpos,joy1ypos;
  307.                 } joypos;
  308.       joypos * is FALSE if the queried joystick is not
  309.       connected.
  310.  
  311. BUGS:
  312. none known
  313.  
  314. SEE ALSO:
  315. readjbutton()
  316.  
  317.  
  318. ubyte readjbutton(void);
  319. read joystick button status
  320.  
  321. FUNCTION:
  322. Query the states of the joystick buttons with readjbutton(). The
  323. lower four bits that are returned in the result ubyte can be
  324. ignored. The button status of the joystick(s) is stored in the
  325. upper four bits:
  326. bit 4 represents joystick #0 button #0
  327. bit 5 represents joystick #0 button #1
  328. bit 6 represents joystick #1 button #0
  329. bit 7 represents joystick #1 button #1
  330. If a joystick button is pressed the corresponding bit is 0 -
  331. else it is 1.
  332.  
  333. INPUTS:
  334. none
  335.  
  336. RESULT:
  337. ubyte buttons: button status of connected joystick(s)
  338.  
  339. BUGS:
  340. none known
  341.  
  342. SEE ALSO:
  343. readstick()
  344.  
  345.